/**
 * @Date: Feb 19, 2010 1:18:14 PM
 */
package com.philip.journal.home.service;

import java.util.List;
import java.util.Map;

import com.philip.journal.home.bean.Branch;
import com.philip.journal.home.bean.Entry;

/**
 * @author cry30
 */
public interface HomeService {

    /**
     * Generates the tree path give the Entry object.
     *
     * @param session - server side session.
     * @param entry - id of the entry from which to generate the tree path.
     * @return String representation of the tree path.
     * @exception IllegalArgumentException when the entry parameter is null.
     */
    String getEntryTreePath(Map<String, Object> session, Entry entry);

    /**
     * Returns the Map of preferences. Root ConfigItem is mapped to null, while child configItem will be mapped to
     * parent ConfigItem matching the ID. Currently this is limited up to children only, no grand children!.
     *
     * @param session - server side session.
     * @return List of Config Items in List of Map format.
     */
    List<Map<String, Object>> getPreferences(Map<String, Object> session);

    /**
     * Moves a folder to another folder.
     *
     * @param session - server side session.
     * @param newParentId - id of the new parent id to put the branch into.
     * @param branchId - id of the branch to move
     * @exception com.philip.journal.core.exception.JournalException thrown when operation has failed to add the new
     *                branch due to the following reasons:
     *                <ul>
     *                <li>branchName already exist for the given parent ID.</li>
     *                <li>supplied parentId does not exist</li>
     *                </ul>
     */
    void moveBranch(Map<String, Object> session, long newParentId, long branchId);

    /**
     * Adds a new branch to the given branchId.
     *
     * @param session - server side session.
     * @param parentId - id of the branch where the newly created branch will be attached to.
     * @param branchName - the name of the branch to be created.
     * @return the id of the created branch
     *
     * @exception com.philip.journal.core.exception.JournalException thrown when operation has failed to add the new
     *                branch due to the following reasons:
     *                <ul>
     *                <li>branchName already exist for the given parent ID.</li>
     *                <li>supplied parentId does not exist</li>
     *                </ul>
     */
    long addBranch(Map<String, Object> session, long parentId, String branchName);

    /**
     * Changes the name of the given branch.
     *
     * @param session server side session.
     * @param parentId Branch ID.
     * @param newBranchName new Branch name.
     * @exception com.philip.journal.core.exception.JournalException when rename fails due to:
     *                <ul>
     *                <li>Name is already exists</li>
     *                <li>Branch with the specified ID does not exist.</li>
     *                </ul>
     */
    void renameBranch(Map<String, Object> session, long parentId, String newBranchName);

    /**
     * Removes the Branch with the given branchId along with all the sub branches.
     *
     * TODO: Current limitation, delete is only allowed on leaves.
     * 
     * @param session server side session.
     * @param branchId branchId of the Branch to delete.
     * @exception com.philip.journal.core.exception.JournalException is thrown when delete operation failed due to:
     *                <ul>
     *                <li>Attempt to delete Root branch.</li>
     *                <li>Branch with the specified ID does not exist.</li>
     *                <li>Concurrency issue, not possible at the moment.</li>
     *                </ul>
     */
    void deleteBranch(Map<String, Object> session, long branchId);

    /**
     * Retrieves the direct sub branches of a given branchId.
     *
     * @param session server side session.
     * @param branchId Id of the Branch whose direct children are to be retrieved.
     * @return List&lt;Branch&gt; containing the direct children of the given branchId.
     */
    List<Branch> getChildren(Map<String, Object> session, long branchId);

    /**
     * Retrieves node properties.
     *
     * @param session server side session.
     * @param nodeId - id of entry or branch.
     * @param isEntry - specifies if the node is a Branch or is an Entry.
     * @return Node properties in a format similar to windows file properties dialog. All properties are intentionally
     *         String type.
     */
    Map<String, Object> getNodeProperties(Map<String, Object> session, long nodeId, boolean isEntry);

}
